ATOM Documentation

← Back to App

Blog Feature Requirements

**Feature Request Date:** 2026-02-18

**Priority:** MEDIUM

**Requested By:** Superadmin / Product Team

Executive Summary

Add a blog platform feature that superadmin and their team can manage to publish product updates, feature announcements, and company news. The blog should be integrated with the existing ATOM SaaS platform and support multi-tenant architecture.

Requirements

1. Blog Post Management

**User Roles:**

  • **Superadmin:** Can create, edit, delete, and publish all blog posts
  • **Team Members:** Can create draft posts, submit for review, publish approved posts
  • **Users:** Can read published blog posts (read-only access)

**Capabilities:**

  • Create blog posts with rich text editor (Markdown support)
  • Edit existing posts (draft or published)
  • Delete posts (with confirmation)
  • Publish/unpublish posts
  • Schedule posts for future publication
  • Save posts as drafts

2. Content Features

**Blog Post Structure:**

{
  id: string;
  title: string;
  slug: string; // URL-friendly (e.g., "new-feature-announcement")
  content: string; // Markdown content
  excerpt: string; // Short summary for listing pages
  author: {
    id: string;
    name: string;
    avatar_url: string;
  };
  status: 'draft' | 'published' | 'scheduled';
  published_at: Date | null;
  scheduled_for: Date | null;
  created_at: Date;
  updated_at: Date;
  tags: string[]; // e.g., ["feature", "announcement", "update"]
  cover_image?: string; // Optional cover image URL
  meta_description?: string; // SEO description
  reading_time_minutes: number; // Auto-calculated
}

**Rich Text Editor:**

  • Markdown syntax support
  • Live preview
  • Code block highlighting
  • Image upload (with automatic optimization)
  • Embed support (videos, tweets, etc.)
  • Autosave (every 30 seconds)

3. Blog Display

**Public Blog Pages:**

  • Blog index page (list of all published posts)
  • Pagination (10 posts per page)
  • Search by title/content
  • Filter by tags
  • Sort by date (newest first)
  • Blog post detail page
  • Full content rendering
  • Table of contents (auto-generated from headings)
  • Author bio section
  • Related posts section
  • Social sharing buttons
  • RSS/Atom feed support

**Admin Blog Pages:**

  • Dashboard with post stats (views, engagement)
  • Post list with filtering (draft, published, scheduled)
  • Post editor (create/edit interface)
  • Media library (images, uploads)
  • Comments moderation (if comments enabled)

4. Multi-Tenancy

**Blog Scope:**

  • **Global blog:** Platform-wide blog managed by superadmin
  • URL: https://atom.ai/blog (primary domain)
  • Shows product updates, company news, feature announcements
  • **Tenant blogs:** Optional per-tenant blogs
  • URL: https://tenant.atom.ai/blog (subdomain)
  • Shows tenant-specific updates, use cases, success stories
  • Can be disabled by tenant

**Configuration:**

// Tenant settings
{
  enable_blog: boolean; // Enable/disable tenant blog
  blog_custom_domain?: string; // Optional custom blog domain
  blog_header?: string; // Custom blog header HTML
  blog_footer?: string; // Custom blog footer HTML
}

5. Database Schema

**New Tables:**

-- Blog posts table
CREATE TABLE blog_posts (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id UUID REFERENCES tenants(id), -- NULL for global blog posts
  title VARCHAR(255) NOT NULL,
  slug VARCHAR(255) NOT NULL UNIQUE,
  content TEXT NOT NULL,
  excerpt TEXT,
  author_id UUID REFERENCES users(id) NOT NULL,
  status VARCHAR(20) NOT NULL DEFAULT 'draft', -- draft, published, scheduled
  published_at TIMESTAMP WITH TIME ZONE,
  scheduled_for TIMESTAMP WITH TIME ZONE,
  cover_image_url TEXT,
  meta_description TEXT,
  tags TEXT[], -- Array of tag strings
  reading_time_minutes INTEGER,
  view_count INTEGER DEFAULT 0,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),

  CONSTRAINT valid_status CHECK (status IN ('draft', 'published', 'scheduled'))
);

-- Indexes for performance
CREATE INDEX idx_blog_posts_tenant_status ON blog_posts(tenant_id, status);
CREATE INDEX idx_blog_posts_slug ON blog_posts(slug);
CREATE INDEX idx_blog_posts_published ON blog_posts(published_at DESC) WHERE status = 'published';
CREATE INDEX idx_blog_posts_tags ON blog_posts USING GIN(tags);

-- Blog media table (images, uploads)
CREATE TABLE blog_media (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id UUID REFERENCES tenants(id),
  post_id UUID REFERENCES blog_posts(id) ON DELETE SET NULL,
  filename VARCHAR(255) NOT NULL,
  original_filename VARCHAR(255) NOT NULL,
  mime_type VARCHAR(100) NOT NULL,
  file_size_bytes INTEGER NOT NULL,
  storage_url TEXT NOT NULL, -- S3 URL
  uploaded_by UUID REFERENCES users(id),
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE INDEX idx_blog_media_tenant ON blog_media(tenant_id);
CREATE INDEX idx_blog_media_post ON blog_media(post_id);

**Row-Level Security:**

-- Enable RLS
ALTER TABLE blog_posts ENABLE ROW LEVEL SECURITY;
ALTER TABLE blog_media ENABLE ROW LEVEL SECURITY;

-- Global blog posts (tenant_id IS NULL) visible to all users
CREATE POLICY blog_posts_global_read ON blog_posts
  FOR SELECT USING (status = 'published');

-- Tenant blog posts visible to tenant users
CREATE POLICY blog_posts_tenant_read ON blog_posts
  FOR SELECT USING (tenant_id = current_setting('app.current_tenant_id')::UUID);

-- Only superadmin can create/edit/delete global posts
CREATE POLICY blog_posts_global_write ON blog_posts
  FOR ALL USING (current_setting('app.is_superadmin')::BOOLEAN);

-- Tenant users can create/edit/delete their own posts
CREATE POLICY blog_posts_tenant_write ON blog_posts
  FOR ALL USING (
    tenant_id = current_setting('app.current_tenant_id')::UUID
    AND (
      author_id = current_setting('app.current_user_id')::UUID
      OR current_setting('app.is_tenant_admin')::BOOLEAN
    )
  );

6. API Routes

**Public Routes (No auth required):**

GET  /api/blog/posts           - List published posts (paginated)
GET  /api/blog/posts/:slug      - Get published post by slug
GET  /api/blog/feed            - RSS/Atom feed
GET  /api/blog/tags             - List all tags
GET  /api/blog/tags/:tag/posts  - Posts by tag

**Protected Routes (Auth required):**

POST   /api/blog/posts           - Create new post (draft)
GET    /api/blog/admin/posts     - List all posts (including drafts)
GET    /api/blog/posts/:id       - Get post by ID (admin view)
PUT    /api/blog/posts/:id       - Update post
DELETE /api/blog/posts/:id       - Delete post
POST   /api/blog/posts/:id/publish - Publish post
POST   /api/blog/posts/:id/unpublish - Unpublish post
POST   /api/blog/upload          - Upload image/media

**Superadmin Only:**

GET  /api/blog/all-posts        - All posts across all tenants
DELETE /api/blog/posts/:id/force - Force delete any post

7. Frontend Components

**Pages:**

  • /blog - Blog index page (public)
  • /blog/:slug - Blog post detail page (public)
  • /admin/blog - Blog admin dashboard (protected)
  • /admin/blog/new - Create new post (protected)
  • /admin/blog/:id/edit - Edit post (protected)

**Components:**

  • BlogPostList - Display list of blog posts
  • BlogPostCard - Single post card for list view
  • BlogPostDetail - Full post content with TOC
  • BlogPostEditor - Markdown editor with preview
  • BlogMediaLibrary - Media management component
  • BlogStats - View count, engagement metrics

8. SEO Features

**Automatic SEO:**

  • Meta tags (title, description, og:image, twitter:card)
  • Structured data (Article, BlogPosting schema)
  • XML sitemap generation
  • Canonical URLs
  • Open Graph tags for social sharing

**URL Structure:**

/blog                                    - Blog index
/blog/new-feature-announcement           - Blog post detail
/blog/page/2                             - Paginated index
/blog/tag/features                        - Posts by tag
/blog/feed                                - RSS feed

9. Success Criteria

  1. ✅ Superadmin can create, edit, publish blog posts
  2. ✅ Team members can create drafts and submit for review
  3. ✅ Public users can read published blog posts
  4. ✅ Blog posts support Markdown with rich text preview
  5. ✅ Multi-tenant support (global + tenant-specific blogs)
  6. ✅ SEO optimized (meta tags, sitemap, structured data)
  7. ✅ Media library for image uploads
  8. ✅ RSS/Atom feed support
  9. ✅ Social sharing integration
  10. ✅ Mobile responsive design

10. Implementation Phases

**Phase 1: MVP (Minimum Viable Product)**

  • Basic blog CRUD operations
  • Markdown editor with preview
  • Public blog pages (index + detail)
  • Superadmin only access
  • Database schema and API routes

**Phase 2: Enhanced Features**

  • Team member access
  • Draft/publish workflow
  • Media library
  • SEO optimization
  • Social sharing
  • RSS feed

**Phase 3: Advanced Features**

  • Tenant-specific blogs
  • Comments system (moderated)
  • Analytics dashboard (views, engagement)
  • Email subscriptions
  • Related posts recommendations
  • Search functionality

**Phase 4: Polish & Scale**

  • Performance optimization (CDN, caching)
  • Internationalization (i18n)
  • Custom themes
  • A/B testing for headlines
  • Advanced analytics (heatmaps, scroll depth)

11. Technical Considerations

**Performance:**

  • Cache blog post HTML (regenerate on edit)
  • CDN for media assets (S3 + CloudFront)
  • Database query optimization (indexes, pagination)
  • Generate static pages for better performance

**Security:**

  • Sanitize all HTML (prevent XSS in blog content)
  • Rate limiting on comment submissions (if enabled)
  • CSRF protection on POST/PUT/DELETE
  • Media upload validation (file types, sizes)
  • RLS policies for multi-tenant isolation

**Scalability:**

  • Separate read replicas for blog read traffic
  • Background job for scheduled post publishing
  • Media processing queue (image optimization, thumbnails)
  • Search indexing (Elasticsearch/Algolia integration)

12. Dependencies

**Existing Systems:**

  • User authentication (already implemented)
  • Tenant management (already implemented)
  • Storage (S3 already configured)
  • Database (PostgreSQL with RLS already configured)

**New Dependencies:**

  • Markdown parser (marked or similar)
  • Rich text editor (Toast UI Editor or similar)
  • Image optimization library (sharp or similar)
  • RSS feed generator (RSS or similar)

13. Testing Strategy

**Unit Tests:**

  • Blog post CRUD operations
  • Slug generation/validation
  • Tag filtering
  • SEO metadata generation
  • Reading time calculation

**Integration Tests:**

  • Blog API endpoints
  • Multi-tenant blog isolation
  • Media upload flow
  • Scheduled post publishing

**E2E Tests:**

  • Blog post creation workflow
  • Publish/unpublish functionality
  • Public blog page rendering
  • SEO tag verification

**Target Coverage:** 85%+ (consistent with v1.7 standards)

---

**Status:** 📋 PLANNED (Not started)

**Priority:** MEDIUM

**Estimated Effort:** 2-3 weeks (4 phases)

**Ready for Implementation:** After v1.7 Platform Hardening complete